The Business Master (3rd Edition)

home *** CD-ROM | disk | FTP | other *** search

/ The Business Master (3rd Edition) / The Business Master (3rd Edition).iso / files / datautil / dscar30 / dscar.doc < prev next >

Wrap

Text File | 1989-07-23 | 91.1 KB | 2,337 lines

dBASE Source Code Analyzer & Reporter ─────────────────────────────────────────────────── .. ....... ....... ...... ...... .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. ........ ....... .. ........ ....... .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. ........ ....... ....... .. .. .. .. ─────────────────────────────────────────────────── Version 3.0 Designed and written by Ryan Katri 2575 Drake Hill Road Fortuna, CA 95540 (707) 725-5559 Copyright (c) 1986-89 by Ryan Katri. All Rights Reserved. TABLE OF CONTENTS ────────────────────────────────────────────────────────────────────── INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 UNREGISTERED VERSION OF dSCAR. . . . . . . . . . . . . . . . . . . . 2 ORDERING dSCAR . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 SYSTEM REQUIREMENTS & DISTRIBUTION . . . . . . . . . . . . . . . . . 4 INSTALLING THE FILES . . . . . . . . . . . . . . . . . . . . . . . . 5 STARTING dSCAR . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 THE MENU SCREEN. . . . . . . . . . . . . . . . . . . . . . . . . . . 7 MENU OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Diagramming. . . . . . . . . . . . . . . . . . . . . . . . . 9 Line Numbers . . . . . . . . . . . . . . . . . . . . . . . .11 Controls Only. . . . . . . . . . . . . . . . . . . . . . . .12 Errors Only. . . . . . . . . . . . . . . . . . . . . . . . .13 Suppress Comments. . . . . . . . . . . . . . . . . . . . . .13 Proc/Funct:. . . . . . . . . . . . . . . . . . . . . . . . .13 Lines 1 to END . . . . . . . . . . . . . . . . . . . . . . .13 X-Reference. . . . . . . . . . . . . . . . . . . . . . . . .14 Modules. . . . . . . . . . . . . . . . . . . . . . . . . . .15 Word Fix-Up. . . . . . . . . . . . . . . . . . . . . . . . .16 Your Reserved. . . . . . . . . . . . . . . . . . . . . . . .17 Comment Condition. . . . . . . . . . . . . . . . . . . . . .17 Screen . . . . . . . . . . . . . . . . . . . . . . . . . . .18 Printer. . . . . . . . . . . . . . . . . . . . . . . . . . .18 File . . . . . . . . . . . . . . . . . . . . . . . . . . . .19 Output Print-Style . . . . . . . . . . . . . . . . . . . . .19 20 Non-stop Scroll. . . . . . . . . . . . . . . . . . . . . . .19 Analyze Another. . . . . . . . . . . . . . . . . . . . . . .19 Install Temporary. . . . . . . . . . . . . . . . . . . . . .20 Save Defaults. . . . . . . . . . . . . . . . . . . . . . . .20 Quit . . . . . . . . . . . . . . . . . . . . . . . . . . . .20 Begin Processing . . . . . . . . . . . . . . . . . . . . . .20 BATCH MODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21 MODULES PROCESSING QUEUE . . . . . . . . . . . . . . . . . . . . . .23 CODING ERRORS dSCAR REPORTS . . . . . . . . . . . . . . . . . . . .24 ADDING RESERVED WORDS. . . . . . . . . . . . . . . . . . . . . . . .25 OTHER FEATURES & TIPS. . . . . . . . . . . . . . . . . . . . . . . .27 CONFIGURING dSCAR. . . . . . . . . . . . . . . . . . . . . . . . . .28 Miscellaneous Settings . . . . . . . . . . . . . . . . . . .29 Install Colors . . . . . . . . . . . . . . . . . . . . . . .33 Printer Setup and Reset. . . . . . . . . . . . . . . . . . .34 INTRODUCTION ────────────────────────────────────────────────────────────────────── dSCAR is a set of utilities for all versions of dBASE, FoxBase, Clipper, FrontRunner, and other dBASE clones. All of the utilities are contained in one user interface and are turned on and off through command line options or the dSCAR menu system. The dSCAR utilities perform a variety of tasks, with these being a few of the highlights: ■ PRETTY-PRINTS SOURCE CODE -- Your code will be more readable with these clean-up functions dSCAR performs: - Properly indents code, lining up all structural statements - Changes variables and reserved words as specified to UPPERCASE/lowercase/SIGNificant case/Proper case - Can comment conditional statements if specified - Optionally removes user comments from source code ■ UNCOVERS ERRORS -- dBASE and its clones do not catch all errors in source code, especially structural errors. dSCAR flags those errors dBASE misses. ■ CREATES FLOW DIAGRAMS -- To aid in reading your source code, dSCAR will add graphic flow diagrams lining up structural statements (like DO WHILE...ENDDO, IF...ENDIF). ■ CONSTRUCTS VARIABLES CROSS-REFERENCES -- Two types of variables cross-references can be created: - Local cross-references display the line numbers where variables are found within a specific module. - Global cross-references are for an entire system, and tell which modules each variable is found in. ■ ADDS LINE NUMBERS -- Line numbering source code is necessary for cross-references, yet it is also useful when analyzing printouts and debugging code. ■ OUTPUTS TO SCREEN, FILE, AND PRINTER -- Send dSCAR output to a variety of devices: - Screen output for quick checking of errors, with all errors being highlighted in specified color. - Printer output adds user-defined header on each page, optionally include page number, module name, system name, copyright notice, and more. A table of contents is also created if a whole system is being documented. - File output so that you can execute your pretty-printed code, or send to a file with printer codes intact for later printing. Page 1 UNREGISTERED VERSION OF dSCAR ────────────────────────────────────────────────────────────────────── The unregistered version of dSCAR is fully functional with no features disabled. The difference between the registered and unregistered versions of dSCAR are the opening and closing screens. The unregistered version has two opening screens: a title screen and an information screen. Pressing any key will page you through the screens. After these screens are displayed the dSCAR menu is presented. The unregistered closing screen is displayed only if you operate dSCAR for more than five minutes at a time. The closing screen urges you to register dSCAR and gives you the option of printing a registration form by pressing the 'R' key. Please do not use this registration form unless the ORDER.EXE program is NOT included with the dSCAR package you received. By registering dSCAR you get the latest version of dSCAR without the opening and closing screens. In addition you will receive a printed manual and unlimited support by phone or by mail. You will also be informed of major dSCAR upgrades and be entitled to updating to newer versions at a nominal charge. See the chapter "ORDERING dSCAR" (next page) for ordering instructions. Page 2 ORDERING dSCAR ────────────────────────────────────────────────────────────────────── Use the ORDER.EXE program to print a registration form. ORDER will request the information needed to register: your name, your company name, your address, and other pertinent information. In addition, it will ask if you are overseas and if you will be sending a purchase order. Both incur additional costs. ORDER will compute sales tax if you are in California and add in the extra cost of overseas shipping and purchase order handling. The total registration cost is displayed on the screen. A check or money order for that amount should be made out and mailed to: Ryan Katri 2575 Drake Hill Road Fortuna, CA 95540 ORDER also allows the entry of optional comments. If you have any suggestions, complaints, or kudos about dSCAR, enter them in the comment area. When all the information is collected, ORDER will print a registration form. Please include the form with your check, money order, or purchase order. This is the current price list for dSCAR v3.0 (prices are subject to change): dSCAR with printed manual..........$ 49.95 each dSCAR without printed manual.......$ 39.95 each dSCAR Unlimited Site License.......$400.00 Add the following if applicable: Sales tax in California............6% on dSCAR base price only Purchase orders less than $100.00..$ 5.00 Overseas shipping..................$ 2.00 Do not compute sales tax on the purchase order handling and overseas shipping costs. Site licenses are unlimited within a single company. dSCAR is supplied on a single disk and with a single printed manual. It is the responsibility of the purchaser to copy disks and print or photocopy manuals. Page 3 SYSTEM REQUIREMENTS & DISTRIBUTION ────────────────────────────────────────────────────────────────────── dSCAR will run on any of the IBM-PC family of computers, including the PC, PC/XT, PC/AT, and PS/2. It should also run on most IBM-compatible machines. If your computer will run dBASE or a dBASE-compatible compiler or interpreter (such as FoxBase, Clipper, etc), then it should also work with dSCAR. The unregistered version of dSCAR is distributed in either the .ZIP or .ARC archive formats. The following files should be included in this archive: DSCAR.EXE - the executable program DSCAR.DOC - dSCAR documentation READ.ME - important last-minute info you should read ORDER.EXE - program to create registration form INSTALL.BAT - installation batch file USE_FOX.BAT - part of installation for FoxBase USE_CLIP.BAT - part of installation for Clipper ASKYN.EXE - used in installation batch file If you received dSCAR on a disk and not in an archive, say from an associate or a software distributor, make sure that all of the above files are present. If any of these files are missing then you received an incomplete package. The READ.ME file may contain some important information which did not get into the manual, so it is recommended that you read this file. If you wish to distribute dSCAR to your associates, distribute only DSCAR??.ZIP. It is illegal to give away a copy of the registered version of DSCAR.EXE. The dSCAR program contained in the .ZIP file contains a functional copy of dSCAR. The only drawback is that it bears two sign-on screens and a closing screen urging the user to register. DSCAR.EXE is the only file necessary to run dSCAR. All other files are optional and dSCAR can operate independent of all of them. Page 4 INSTALLING THE FILES ────────────────────────────────────────────────────────────────────── To copy the dSCAR files over to another floppy disk or hard disk, first log into the drive and directory you want to put dSCAR on. Then, put the distribution disk in another drive and type: <drive>:INSTALL <drive>: <drive> is the drive letter where the dSCAR distribution disk is located. If this is drive A:, you would type: A:INSTALL A: Install performs two functions. First, it copies DSCAR.EXE from the distribution disk to the current drive and directory. Secondly, it asks if you are using Clipper or FoxBase. If you are using Clipper or FoxBase then the install program will create a RESERVED file in the current directory. The RESERVED file contains language extensions for the cross-reference feature of dSCAR. See the chapter titled "ADDING RESERVED WORDS" (page 25) for more information. For now you can ignore the RESERVED file. You do not have to use the install program to copy dSCAR. DSCAR.EXE is the only necessary file to operate dSCAR, and it may be copied to other directories and disks using the Dos COPY command. If you are using a hard disk it is recommended you just put DSCAR.EXE in a directory found in your path statement. If you wish to configure dSCAR at this point, turn to the chapter heading "CONFIGURING dSCAR" (page 28). It is recommended, however, that you run and familiarize yourself with dSCAR before making any changes in configuration. Page 5 STARTING dSCAR ────────────────────────────────────────────────────────────────────── To start dSCAR, at the DOS prompt type: DSCAR <return> If dSCAR is in the current directory or one of your path statements, the options menu will be displayed and the second line of the screen will prompt: dBASE file to process: *.PRG '*.PRG' is the default file mask. Press <return> if you want to get a list of all of the files with a .PRG extension. Or, type in the name of the dBASE program file you wish to process. Path designations are acceptable. <ESC> will exit dSCAR. A quicker way to bring up dSCAR is to include the file to process on the command line. The syntax is: DSCAR <filename> <return> Where <filename> is the name of the dBASE file to be processed. Wildcards are acceptable in filenames. If a wildcard is entered at the 'dBASE file to process' prompt, dSCAR will open up a window displaying a list of the files matching the filespec. You can then scan the list using the <Up Arrow>, <Down Arrow>, <Page Up>, <Page Down>, <Home>, and <End> keys. Pressing a letter 'A'-'Z' will move the cursor to the first filename beginning with that letter. <Return> will select the file the cursor is positioned on. Page 6 THE MENU SCREEN ────────────────────────────────────────────────────────────────────── The dSCAR menu screen is divided into three areas: the status lines, the selection window, and the installation window. Each of these areas is explained in detail: ■ Status Lines The status lines are the top three lines of the screen. They contain the dSCAR version number and copyright notice, the file which is selected to be processed, and the output device or filename. A sample status line is shown: dSCAR v3.0 (Copyright (c) 1986-89 Ryan Katri) dBASE file to process: MAIN.PRG Output file: (screen) The output file will show a filename if output is to a file. It will display '(printer)' or '(screen)' if output is to one of these two devices. ■ Selection Window The selection window displays the options which may be turned on or off. The window looks like this: ╔═════════════════════════════════════════════════╗ ║ -FLOW CONTROLS- -DOCUMENTATION- ║ ║ ║ ║ D Diagramming X X-Reference ║ ║ L Line numbers M Modules ║ ║ C Controls only W Word fix-up ║ ║ E Errors only Y Your reserved ║ ║ * Suppress comments & Comment condition ║ ║ = Proc/Funct: ║ ║ # Lines 1 to END ║ ║ ║ ║ -OUTPUT OPTIONS- -ACTIONS- ║ ║ ║ ║ S Screen A Analyze another ║ ║ P Printer I Install temporary ║ ║ F File ! Save defaults ║ ║ O Output print-style Q Quit ║ ║ N Non-stop scroll ║ ║ ║ ║ RETURN: Begin Processing ║ ╚═════════════════════════════════════════════════╝ Selected (turned on) options are highlighted. 'Flow Controls', 'Documentation', 'Output Options', and 'Actions' are the option headings. Page 7 You can toggle options on and off by hitting the key next to the option. For example, to turn Diagramming on and off, hit the 'D' key. Some options are not toggles, specifically those under the Actions heading. Pressing <return> will start processing the selected program file. ■ Installation Window The installation window resembles the following: ┌───── CONFIGURATION ────┐ │ │ │ Indent Count : 3 │ │ Diagram Type : G │ │ Reserved Case : U │ │ Variables Case : P │ │ Printer Port : 1 │ │ Screen Length : 22 │ │ Printer Length : 63 │ │ Printer Width : 80 │ │ File Width : 79 │ │ Module Extension: PRG │ │ Print-Style Ext.: PRN │ │ Output Extension: FLO │ │ X-Ref Extension : XRF │ │ Truncate Lines : N │ │ │ ├──── RESERVED WORDS ────┤ │ # Own Reserved : 4 │ └────────────────────────┘ Contained under the Configuration heading of this window are many of the settings you can control through dSCAR's configuration program. These settings can be modified for a single dSCAR session, however, by selecting the option Install Temporary. Thus, you can on-the-fly change many of dSCAR's setting, such as the printer port to use or the indent count. If you change these settings from the menu screen, they are changed for that session only. To make permanent changes you must run dSCAR's built-in configuration program. The Reserved Words heading tells how many reserved words are defined. This feature is explained in a later section. Page 8 MENU OPTIONS ────────────────────────────────────────────────────────────────────── ■ DIAGRAMMING -- 'D' key toggles on/off One of the most useful features of dSCAR is its ability to line up all your control statements to make sure they are structurally sound. This makes it easy, for example, to see where you might have an open CASE or a missing IF. dBASE will not catch structural errors, yet structural errors usually result in erratic operation of your program. If your program is making some weird returns or executing loops improperly, dSCAR can be called upon to see if the problem is structural. Most dBASE language compilers (ie Clipper) will warn of structural errors themselves. Below is a sample of code before it has been processed with dSCAR's Diagramming option: ┌─CODE BEFORE PROCESSING─────────────────────────────────────┐ │ │ │ DO WHILE .T. │ │ ACCEPT 'What is your name?' TO Myname │ │ IF UPPER(Myname) <> 'JOE' │ │ ? 'Only Joe is allowed access!' │ │ RETURN │ │ ELSE │ │ ? 'Hello Joe' │ │ DO CASE │ │ CASE Myname = 'JOE' │ │ ? 'You typed in uppercase' │ │ CASE Myname = 'joe' │ │ ? 'You typed in lowercase' │ │ RETURN │ │ ENDCASE │ │ ENDIF │ │ ENDDO │ └────────────────────────────────────────────────────────────┘ The resulting output with Diagramming on would look something like this: ┌─GRAPHIC FLOW DIAGRAMS──────────────────────────────────────┐ │ │ │ ╓DO WHILE .T. │ │ ║ ACCEPT 'What is your name?' TO Myname │ │ ║ ┌IF UPPER(Myname) <> 'JOE' │ │ ║ │ ? 'Only Joe is allowed access!' │ │ ────────RETURN │ │ ║ ├ELSE │ │ ║ │ ? 'Hello Joe' │ │ ║ │ ╒DO CASE │ │ ║ │ ╞CASE Myname = 'JOE' │ Page 9 │ ║ │ │ ? 'You typed in uppercase' │ │ ║ │ ╞CASE Myname = 'joe' │ │ ║ │ │ ? 'You typed in lowercase' │ │ ────────────RETURN │ │ ║ │ ╘ENDCASE │ │ ║ └ENDIF │ │ ╙ENDDO │ └────────────────────────────────────────────────────────────┘ The above example assumes that graphic flow diagrams are selected. Graphic diagrams use single and double lines to show how your program's flow is structured. Double lines are used for DO WHILE and DO CASE statements, while single lines for IF statements. Horizontal lines are used to indicate where the flow jumps to when a RETURN, LOOP, or EXIT is encountered. You can change from graphic flow diagrams to text diagrams through the configuration or temporary installation. Text diagrams are not as attractive, but they are more informative if you are trying to figure out the flow of a program. Here is what a text flow diagram looks like: ┌─TEXT FLOW DIAGRAMS─────────────────────────────────────────┐ │ │ │ DO WHILE .T. │ │ W ACCEPT 'What is your name?' TO Myname │ │ W IF UPPER(Myname) <> 'JOE' │ │ W T ? 'Only Joe is allowed access!' │ │ <--------RETURN │ │ W ELSE │ │ W F ? 'Hello Joe' │ │ W F DO CASE │ │ W F CASE Myname = 'JOE' │ │ W F 1 ? 'You typed in uppercase' │ │ W F CASE Myname = 'joe' │ │ W F 2 ? 'You typed in lowercase' │ │ <------------RETURN │ │ W F ENDCASE │ │ W ENDIF │ │ ENDDO │ └────────────────────────────────────────────────────────────┘ Notice that each control statement has a corresponding character to represent it. For example, a WHILE structure is lined up with a W. Below is what each character in the text flow diagram represents: W - DO WHILE; terminates with ENDDO T - IF is true; terminates with ENDIF or ELSE F - ELSE is false; terminates with ENDIF Page 10 S - SCAN; terminates with ENDSCAN C - DO CASE; terminates with first CASE, OTHERWISE, or ENDCASE # - Number of the case statement; terminates with next CASE, OTHERWISE, or ENDCASE O - OTHERWISE; terminates with ENDCASE P - PRINTJOB; terminates with END PRINTJOB L - FOR; terminates with NEXT If you don't quite understand these, try running some of your dBASE code through dSCAR with Diagramming on and you will get the picture. If you want runnable code that is simply indented without the flow diagramming, then turn Diagramming off. Code processed with all flow control options turned off is still indented and can be executed by dBASE and interpreted by a compiler. ■ LINE NUMBERS -- 'L' key toggles on/off Line Numbering will add line numbers to your source code. If Variables Cross-Reference is on, then it is recommended to have Line Numbering on, as the variables are referenced with the corresponding line numbers. There are two ways to line number. The default method is to have each complete line of source code assigned its own number. The second method gives each continuation line its own number. For example, if a long line of code will not fit on a single line, dSCAR will automatically break it up into several lines using the dBASE continuation feature; each continued line would be assigned a new line number. An example of numbering if each complete line of source code is to have a single line number: ┌─SINGLE NUMBER FOR CONTINUATION LINES───────────────────────┐ │ │ │ 1 do while .not. eof() │ │ 2 replace first with mfirst, last with mlast,; │ │ 2 company with mcompany, phone with mphone,; │ │ 2 address1 with maddress1, address2 with maddress2 │ │ 3 skip │ │ 4 enddo │ └────────────────────────────────────────────────────────────┘ An example of numbering if continuation lines are assigned new numbers: Page 11 ┌─NEW NUMBERS FOR CONTINUATION LINES─────────────────────────┐ │ │ │ 1 do while .not. eof() │ │ 2 replace first with mfirst, last with mlast,; │ │ 3 company with mcompany, phone with mphone,; │ │ 4 address1 with maddress1, address2 with maddress2 │ │ 5 skip │ │ 6 enddo │ └────────────────────────────────────────────────────────────┘ The numbering method can be specified through the dSCAR configuration. ■ CONTROLS ONLY -- 'C' key toggles on/off This option tells dSCAR to only include the control lines in the output. These control lines would be commands such as DO CASE/OTHERWISE/ENDCASE, IF/ELSE/ENDIF, DO WHILE/ENDDO, IF/ELSE/ENDIF, SCAN/ENDSCAN, FOR/NEXT, and PRINT/END PRINTJOB. This option is usually used in conjunction with the Diagramming function. The utility of Controls Only is that you can view the structure of your program without having to read through the extraneous code which has no effect on structure. Below are examples of source code with Controls Only off and with Controls Only on (in both cases Diagramming is turned on): ┌─CONTROLS ONLY OFF──────────────────────────────────────────┐ │ │ │ ╓do while .t. │ │ ║ accept 'What is your name?' to myname │ │ ║ ┌if upper(myname) <> 'JOE' │ │ ║ │ ? 'Only Joe is allowed access!' │ │ ────────return │ │ ║ ├else │ │ ║ │ clear │ │ ║ │ ? 'Hello Joe' │ │ ║ │ ? 'Do you wish to check your messages now? │ │ ║ │ accept to CheckMsg │ │ ║ │ ╒do case │ │ ║ │ ╞case CheckMsg = 'Y' │ │ ║ │ │ do CheckIt │ │ ║ │ ╞case CheckMsg = 'N' │ │ ║ │ │ ? 'Thank you for logging in.' │ │ ────────────return │ │ ║ │ ╘endcase │ │ ║ └endif │ │ ╙enddo │ └────────────────────────────────────────────────────────────┘ Page 12 ┌─CONTROLS ONLY ON───────────────────────────────────────────┐ │ │ │ ╓do while .t. │ │ ║ ┌if upper(myname) <> 'JOE' │ │ ────────return │ │ ║ ├else │ │ ║ │ ╒do case │ │ ║ │ ╞case CheckMsg = 'Y' │ │ ║ │ ╞case CheckMsg = 'N' │ │ ────────────return │ │ ║ │ ╘endcase │ │ ║ └endif │ │ ╙enddo │ └────────────────────────────────────────────────────────────┘ Notice how much easier it is to follow the flow when Controls Only is turned on. ■ ERRORS ONLY -- 'E' key toggles on/off With Errors Only on, only errors that are found in the dBASE code are displayed. When Errors Only is selected, the following options are automatically turned off: Line Numbers, Controls Only, Suppress Comments, and Diagramming. See "CODING ERRORS dSCAR REPORTS" (page 24) for a list of the errors. ■ SUPPRESS COMMENTS -- '*' toggles on/off You can filter the comments out of your code by turning this option on. Useful to see only the necessary code for debugging. ■ PROC/FUNCT: -- '=' prompts for entry of procedure or function dSCAR will process only the selected procedure or function if you indicate it here. dSCAR will scan through your dBASE program files until it encounters the selected procedure or function. Only that procedure or function will be processed. When you select this option dSCAR will ask for the procedure or function to process. The maximum length of a procedure name is 10 characters. If you wish to turn this features off (it is not a toggle) after already entering a procedure, just delete the procedure name you had entered using the DELete key on the keyboard. ■ LINES 1 TO END -- '#' prompt for a beginning and ending line You can optionally select to have dSCAR process only a specific range of line numbers in a module. For example, you may want to process only up through line 50 in your program. Or, if you want to process only lines 100 to 150, you can save time by skipping the first 99 Page 13 lines and everything after line 150. When entering a beginning line number, an entry of '0' or '1' means to start from the beginning of the program. To have dSCAR process all the way to the end of the program, enter '0' when prompted for the ending line number. This option only works with single modules. Turning it on will automatically turn Modules off. ■ X-REFERENCE -- 'X' toggles on/off Turning Variables Cross-Reference on will instruct dSCAR to prepare a cross-reference of all variables as it processes each module. There are two types of cross-references: local and global. A local cross-reference includes only variables found in one module or procedure, and indicates on which line numbers found. A global cross- reference displays the modules each variable is found in. If Variables Cross-Reference is toggled on, it is recommended that Line Numbers be turned on, as variables are referenced by their line numbers in a local cross-reference. If Modules is selected, then a global cross-reference will be created; otherwise, only a local cross- reference is generated. The local cross-reference is displayed after each individual module or procedure is processed. The listing for a local cross-reference is in a format similar to this: ┌─LOCAL CROSS-REFERENCE──────────────────────────────────────┐ │ │ │ Variable Line number in file │ │ -------- ------------------- │ │ CheckMsg: 11 13 15 │ │ myname: =2 3 4 │ └────────────────────────────────────────────────────────────┘ 'CheckMsg' and 'myname' are variables. 'CheckMsg' occurs in lines 11, 13, and 15. 'myname' is found in lines 2, 3, and 4. Notice the equal sign (=) next to the 2 after 'myname.' The equal sign indicates that on line 2 'myname' is assigned a new value. All variable assignments are indicated with the equal sign, as well as being highlighted if output is to the screen. If Modules is toggled on also, then a global cross-reference of variables will also be generated. The global cross-reference quickly shows which variables occur in which modules. If a variable occurs in a procedure, then the procedure name is displayed with the module name in parenthesis beside it. A sample global cross-reference is shown: Page 14 ┌─GLOBAL CROSS-REFERENCE─────────────────────────────────────┐ │ │ │ Variable occurs in Modules │ │ -------- ------- │ │ CheckMsg: TEST.PRG │ │ myname: SHOWNAME(GETNAME.PRG) GETNAME.PRG │ │ TEST.PRG │ │ NoName: SHOWNAME(GETNAME.PRG) │ │ TempName: GETNAME.PRG │ └────────────────────────────────────────────────────────────┘ 'CheckMsg' occurs only in the TEST.PRG module. 'myname' occurs in two modules and one procedure. The procedure name is SHOWNAME, and SHOWNAME is in the module GETNAME.PRG. 'NoName' is found solely in a procedure, and TempName occurs in a single module. ■ MODULES -- 'M' key toggles on/off Turning Modules on will instruct dSCAR to process all modules that may call each other in a complete dBASE system. Any time dSCAR encounters a DO <filename>, SET FORMAT TO <filename>, or SET PROC TO <filename> it will add the filename to a list of modules to be processed. Thus, if you had several modules to process, and they are all eventually called somewhere in the system, you could start with the top module and dSCAR will work down from there. To illustrate this: You have a module called MAIN.PRG, which calls ACCOUNTS.PRG and INVENT.PRG. ACCOUNTS.PRG in turn calls EDIT.PRG, and INVENT.PRG also calls EDIT.PRG. If you turn Modules on and start with the file MAIN.PRG, then all of these would get processed: MAIN.PRG, ACCOUNTS.PRG, INVENT.PRG, and EDIT.PRG. A module will NOT be processed twice! The current module being processed is written at the bottom of the screen. This makes it easy to see what modules have errors in them with a glance at the status line. Depending on what you specified in the configuration, drive designators and path names will or will not be stripped from filenames. If pathnames are stripped, then dSCAR will search for modules first in the current directory. If a module is not found in the current directory, dSCAR will search the directory in which the top module was specified to be in. If a file cannot be found a warning message is displayed to the Page 15 screen. Sometimes dSCAR will not find a module because the module is really a procedure. In this case, ignore the warning message. If you wish to process a module as part of a system but that module is not being called by the system, use the MODULES file. This is a file containing a list of modules you want added to the processing queue. See the chapter heading "MODULES PROCESSING QUEUE" (page 23) to see how to do this. ■ WORD FIX-UP -- 'W' key toggles on/off Word Fix-up will fix your code cosmetically by changing the case of reserved words and variables in your code. For example, you may opt to capitalize all reserved words and lowercase variables. You specify the case for reserved words and variables in dSCAR configuration. It may also be changed through the temporary installation. There are five different ways to change the case of reserved words and variables: upper, lower, proper, significant, and no change. Upper and lower are self-explanatory. In proper case, the first letter of each word is capitalized. For example, 'do while' becomes 'Do While' and 'REPLACE' becomes 'Replace'. Significant case will capitalize only the first four letters of a word. 'do while' becomes 'DO WHILe' and 'replace' becomes 'REPLace.' No change will leave all reserved words or all variables as they are found in the code. This is especially useful if you want to change the case of reserved words, but leave variables as you entered them. Below is an example of code before and after processing with Word Fix- up on. In this case, reserved words are capitalized and variables are made proper case. ┌─CODE BEFORE PROCESSING─────────────────────────────────────┐ │ │ │ do while .T. │ │ Accept 'What is your name?' to myname │ │ IF upper(MYNAME) <> 'JOE' │ │ ? 'Only Joe is allowed access!' │ │ return │ │ ELSE │ │ ? 'Hello Joe' │ │ retu │ │ endif │ │ enddo │ └────────────────────────────────────────────────────────────┘ Page 16 ┌─WORD FIX-UP ON─────────────────────────────────────────────┐ │ │ │ DO WHILE .T. │ │ ACCEPT 'What is your name?' TO Myname │ │ IF UPPER(Myname) <> 'JOE' │ │ ? 'Only Joe is allowed access!' │ │ RETURN │ │ ELSE │ │ ? 'Hello Joe' │ │ RETU │ │ ENDIF │ │ ENDDO │ └────────────────────────────────────────────────────────────┘ Keep in mind that Word Fix-up will not add or delete any code. If you always use only the first four letters for dBASE commands and functions, dSCAR will not expand the word. For example, if you used 'retu' in your code, dBASE would make that 'RETU' (as shown in the code sample above). It will not expand it to be 'RETURN'. ■ YOUR RESERVED -- 'Y' key toggles on/off In order to support the ever-changing and expanding dBASE language and dBASE clones, dSCAR allows you to add your own reserved words to its own list. The main purpose of this is to keep those new commands which dSCAR does not recognize out of the cross-reference. Your own reserved words are contained in a file called RESERVED (no extension). If dSCAR finds this file in the current directory then Your Reserved is automatically toggled on. The words contained in RESERVED are read into dSCAR's list of reserved words and will no longer be added to a cross-reference of variables. If you do not wish to use the reserved words in RESERVED, then turn Your Reserved off. The point of this is if you happen to be using two different dBASE compatible languages. For example, you might use Clipper at times and dBASE IV at other times. You will need the extra reserved words when processing Clipper code, so you would want Your Reserved toggled on. However, when processing dBASE IV code you would want it toggled off, as all of dBASE IV's reserved words are part of dSCAR's internal list. See the chapter "ADDING RESERVED WORDS" (page 25) for instructions on creating your own reserved words list. ■ COMMENT CONDITION -- '&' toggles on/off dSCAR can aid in commenting your source code. If Comment Condition is on, dSCAR will append the condition for an IF, DO WHILE, SCAN, and FOR to the finishing ENDIF, ENDDO, ENDSCAN and NEXT. For example, take the following statement: IF x = 10 Page 17 When dSCAR encounters the ENDIF, it will add a comment like this: ENDIF && x = 10 By doing so, it makes it easy to see what an ENDIF, ENDDO, or NEXT is terminating. If there is already a comment on the ENDIF, ENDDO, or NEXT line, then dSCAR will leave the original comment intact and not add its own comment. ■ SCREEN -- 'S' key turns on, 'P', 'F', or 'O' turns off Hit the 'S' key if you want all output to go to the screen. dSCAR will pause after a screen page is displayed unless Non-stop Scroll is toggled on. After a page is displayed, dSCAR will prompt with the following message: Q to quit, N for non-stop, any other key to continue. Hitting 'Q' or <ESC> will return you to the dSCAR main menu. 'N' will make the display non-stop so it will not pause after each page. However, you can force a pause at any time by hitting the <ESC> key; you can then turn non-stop scrolling off if you wish. Pressing a key besides 'Q' or 'N' will display the next screen page. At the end of processing the entire system, dSCAR will display this message: [END OF ANALYSIS] Q to quit dSCAR, any other key for menu Pressing 'Q' or <ESC> at this point will exit dSCAR completely. Any other key will return you to the main menu. ■ PRINTER -- 'P' key turns on, 'S', 'F', or 'O' turns off Hit the 'P' key if you want all output to be directed to the printer. When sending output to the printer, dSCAR will initially send the optional codes specified to set up the printer. At the end of printing it will send the codes to reset the printer. These printer codes are specified in the dSCAR configuration. There are several other printer options which are specified in the configuration. These include the left margin, page length and width, the page heading, printer port to use, and whether or not a formfeed is sent after each module is printed. See the chapter heading "CONFIGURING dSCAR" (page 28) for more information on these options. When Errors Only is toggled on and output is to the printer, each module processed is separated by dashes instead of a formfeed. Hitting <ESC> will pause printing and ask if you wish to abort. Page 18 ■ FILE -- 'F' key turns on, 'S', 'P', or 'O' turns off Hit the 'F' key to send output to disk. Sending output to the disk is most useful when you want to pretty up your source code to make it more readable as you work on it. To do this and still have runnable code, you must turn Diagramming and Line Numbers off. Output to disk is sent to the same filename of each module but with a new extension. For example, the source code will be written to the same filename as the module being processed, but the extension will be '.FLO'. The local cross-reference will go to the filename of the referenced module but with an extension of '.XRF'. The global cross- reference will be written to the same filename as the top file, but with an extension of '.GBL'. All of these extensions may be changed through the dSCAR configuration. For example, if you process the file HELP.PRG, the output file will be HELP.FLO. If a local cross-reference is generated it will go to HELP.XRF. If Modules and X-Reference is turned on, then the global cross-reference will be HELP.GBL if HELP.PRG is the top module. ■ OUTPUT PRINT-STYLE -- 'O' key turns on, 'S' 'P', or 'F' turns off Hit the 'O' key to send output to disk but in printing format. This is necessary if you want to print the documentation later from the file, as all formfeeds, page headings, and margins will be left intact. When you select output to disk print-style, dSCAR will request a filename to send the output to. If you enter a specific filename then all output will go to a single file--this includes source code, local cross-references, and the global cross-reference. If '*.*' is entered as the output file, then each module and cross- reference will go to a separate file, just like output to file operates. For example, HELP.PRG will make two files: HELP.FLO and HELP.XRF. The difference between these files and those generated by output to file is that these will have printer codes inserted. ■ NON-STOP SCROLL -- 'N' key toggles on/off Non-stop Scroll will restrict dSCAR from pausing after a full page is displayed when output is to the screen. You can still press the <ESC> key at any time to pause the output. ■ ANALYZE ANOTHER -- 'A' key prompts for a new file to process To get another file to process, hit the 'A' key. This will ask for a new file to process. Hitting <ESC> will abort the entry and return to the original file being processed. Page 19 ■ INSTALL TEMPORARY -- 'I' key selects You can change many dSCAR options on-the-fly by Installing Temporary. Changes made here are for one session only. Once dSCAR is terminated all temporary installation settings are lost. If you wish to make a permanent change, use the dSCAR configuration. When you hit the 'I' key to Install Temporary, you are thrown into the installation window. Using the up and down arrow keys go to the option you wish to change and enter the new value. Pressing <ESC> will save the temporary settings and return to the selection window. For a detailed discussion of each setting, see the configuration instructions under the chapter heading "CONFIGURING dSCAR" (page 28). ■ SAVE DEFAULTS -- '!' prompts for file and saves defaults When dSCAR is initiated, the menu options have default settings. For example, Diagramming and Comment Condition are turned on and output is to the screen. You may find that you are continually using dSCAR with different settings, such as Modules and Line Numbering turned on, Diagramming off, and output to file. You can make these settings the default with the Save Defaults command. To save your defaults, toggle all menu options to the desired state. When all the options are how you want them to permanently be, type '!'. dSCAR will then prompt for the filename of dSCAR. This is usually DSCAR.EXE, but if you renamed dSCAR then you must enter the new name. The new menu defaults will be saved so that they are the defaults the next time dSCAR is loaded. Note that Save Defaults does NOT save the Temporary Installation settings. ■ QUIT -- 'Q' or <ESC> key To exit dSCAR, press 'Q' or hit <ESC>. ■ BEGIN PROCESSING -- <return> begins processing Hit <return> to start processing the selected module with the desired options. If output is to the printer and the printer is not ready or turned on, dSCAR will not begin processing. Page 20 BATCH MODE ────────────────────────────────────────────────────────────────────── dSCAR can be operated completely from the command line, bypassing the menu screen. Thus, you can write a batch file for dSCAR to have it process several systems at one time while you are away from the computer. The command line format for batch is: DSCAR <filename> {BCDEFLMOPSWXY}{=<procedure>/} {-begin line/}{+end line/}{(outfile)} <filename> is the name of the dBASE file to process. Everything between the curly braces ({}) are optional, except that there must be at least one parameter after <filename> to send dSCAR into batch mode. Spaces should not separate the parameters after <filename>. To invoke dSCAR in batch mode with the default settings, use this format: DSCAR <filename> B The above command line tells dSCAR to process <filename> in batch mode ('B' indicates batch). When in batch mode dSCAR will not pause after displaying a page, nor will it return to the menu screen, but instead exit back to DOS. You can also set processing options from the command line. Do this by including on the command line the selection key for the menu option you wish to toggle from its default state. For example, if you wish to toggle Diagramming off (on is the default) and send output to a file instead of the screen, use this command line: DSCAR <filename> DF Notice that the 'B' is not needed. 'B' is only needed if you are not toggling any options but wish to use the defaults. However, including the 'B' parameter at other times will not hurt. There are two things you must remember when operating in batch mode: the selection keys for the menu options and the default menu settings. For example, the 'D' key turns Diagramming off and on, and Diagramming on is the default. Several options are not supported from batch mode, for obvious reasons. These include Non-stop Scroll, Analyze Another, Install Temporary, and Save Defaults. Specifying a procedure/function or beginning and ending line numbers to process requires a special format. For a procedure or function, include the name of the procedure/function between an equal sign (=) Page 21 and a slash (/). For example, the following command will process the procedure HELP with diagramming turned off: DSCAR <filename> D=HELP/ To specify the low range of line numbers to process, include the beginning line number between a minus sign (-) and a slash (/). This command line will process <filename> beginning at line 113: DSCAR <filename> -113/ The high range line number is included between a plus sign (+) and a slash (/), like this: DSCAR <filename> +200/ Suppose you wanted to process from line 110 to line 150. To do this you would enter: DSCAR <filename> +150/-110/ Notice that the order of the parameters makes no difference. You can also specify an output file on the command line. Do this by including the output filename between parenthesis. For example, to send output print-style (option 'O') to the file PRINT.XYZ, use this command line: DSCAR <filename> O(PRINT.XYZ) You will have to experiment with the batch mode in order to get the hang of it. Here are a few more examples, as examples illustrate best in this case: DSCAR <filename> DMXL (Diagramming off, Modules on, X-ref on, Numbering on) DSCAR <filename> D+100/L (Diagramming off, end at line 100, Numbering on) DSCAR <filename> E=WRITE/ (Errors Only on, procedure WRITE) Page 22 MODULES PROCESSING QUEUE ────────────────────────────────────────────────────────────────────── Even with Modules turned on dSCAR will not always process every module in your system. The usual reason for this is macros. For example, you may have some code which looks like this: ┌─MODULES & MACROS───────────────────────────────────────────┐ │ │ │ IF Option = 1 │ │ Do_file = 'MENU_1' │ │ ELSE │ │ Do_file = 'MENU_2' │ │ ENDIF │ │ DO &Do_file │ └────────────────────────────────────────────────────────────┘ dSCAR has no way of knowing that 'Do_file' is not the name of a file and that MENU_1 and MENU_2 are files. To process these modules as part of a system you can add them to a MODULES file. When dSCAR is executed with Modules turned on, it looks for the existence of MODULES and reads the filenames contained in it into the processing queue. MODULES is a straight ascii file. The filenames in it are separated by a carriage return/linefeed pair. Thus, for the above example, MODULES would looks like this: ┌─SAMPLES MODULES FILE───────────────────────────────────────┐ │ │ │ MENU_1.PRG │ │ MENU_2.PRG │ └────────────────────────────────────────────────────────────┘ The filenames need not be in any particular order. Be sure to delete the MODULES file when you are done with it or the modules contained in it may be processed for systems they are not needed for. Page 23 CODING ERRORS dSCAR REPORTS ────────────────────────────────────────────────────────────────────── The following is a list and explanation of the structural errors commonly found in source code which dSCAR reports. ■ Open IF from line #### -- if there is an IF statement without a matching ENDIF dSCAR attempts to track down which IF statement was left open. ■ Open WHILE from line #### -- DO WHILE has no terminating ENDDO ■ Open CASE from line #### -- DO CASE has no terminating ENDCASE ■ Open TEXT from line #### -- TEXT has no terminating ENDTEXT ■ Open FOR from line #### -- FOR has no terminating NEXT ■ Open SCAN from line #### -- SCAN has no terminating ENDSCAN ■ Open PRINT from line #### -- PRINT has no terminating END PRINTJOB ■ ENDIF without IF or ELSE -- an ENDIF has no matching IF or ELSE statement ■ ELSE without IF -- an ELSE statement was found with no matching IF statement ■ ENDDO without DO WHILE -- ENDDO has no matching DO WHILE ■ ENDCASE without DO CASE -- ENDCASE has no matching DO CASE ■ ENDSCAN without SCAN -- ENDSCAN has no matching SCAN ■ END PRINT without PRINT -- END PRINTJOB has no matching PRINT ■ NEXT without FOR -- NEXT has no matching FOR ■ ENDCASE without DO CASE -- ENDCASE has no matching DO CASE ■ Unexpected ENDTEXT -- ENDTEXT has no matching TEXT ■ Missing DO CASE statement -- a CASE or OTHERWISE statement is missing the DO CASE ■ Empty DO CASE -- DO CASE is immediately followed by ENDCASE with no CASE ■ DO CASE not followed by CASE -- a CASE should immediately follow a DO CASE ■ Follows LOOP never executed -- the only valid code to immediately follow a LOOP is ELSE, ENDIF, CASE, OTHERWISE, or ENDCASE ■ Follows EXIT never executed -- the only valid code to immediately follow an EXIT is ELSE, ENDIF, CASE, OTHERWISE, or ENDCASE ■ After RETURN never executed -- code after a RETURN is ignored unless the code is a procedure, an ELSE, ENDIF, CASE, OTHERWISE, or ENDCASE ■ Warning:At most 1 iteration -- a SCAN and DO WHILE will only iterate once if a LOOP, EXIT, or RETURN is nested one level beneath the SCAN or DO WHILE ■ Redundant LOOP statement -- a LOOP nested one level beneath a DO WHILE will cause the DO WHILE to be executed over and over again. Make sure a LOOP is embedded in a conditional structure such as IF...ENDIF. ■ Not within a DO WHILE -- an EXIT must be within a DO WHILE or LOOP structure, and a LOOP must be within a DO WHILE structure ■ SET PROC not followed by TO ■ SET FORM not followed by TO Page 24 ADDING RESERVED WORDS ────────────────────────────────────────────────────────────────────── Most dBASE compilers and dBASE-compatible interpreters have additional commands and reserved words not supported by dBASE itself. dSCAR has internal built-in support for dBASE. However, if you are using a compiler such as Clipper or interpreter such as FoxBase, dSCAR supports their language extensions through external files. The file RESERVED (no extension) contains extra reserved words. The words contained in this file will not be added to any cross- references. RESERVED contains reserved words which are found within a line. Examples include ALL, TO, WHILE, and STATUS. You do not need to add commands (those words which appear first on a line), as dSCAR will always recognize a command when it sees one. Therefore, command words should not be added to the RESERVED list. Examples of commands include DO, SET, CREATE, and RETURN. Included in the distribution of dSCAR are two batch files: USE_FOX.BAT and USE_CLIP.BAT. If you are using FoxBase then run the batch file USE_FOX. This will create the necessary RESERVED file for use with FoxBase. Executing the USE_CLIP batch file will do the same for Clipper. You can modify or create your own RESERVED file using a text editor. The file is straight ascii. Each word is on a single line separated by a carriage return/linefeed pair. The words do not have to be in any particular order. RESERVED must reside in the current directory. If you use both Clipper and FoxBase or any other dBASE-compatible product, you can put different RESERVED lists in different directories. Thus, when you are processing Clipper code, dSCAR will use the appropriate reserved words if you are in the Clipper directory. dSCAR will use the FoxBase set of words when in the FoxBase directory. dSCAR automatically detects if the RESERVED file is present and turns Your Reserved on as needed. Page 25 dSCAR's reserved word list includes all of those found in dBASE IV. If you are unsure whether or not dSCAR supports a reserved word which is found in your dBASE compiler or interpreter, check the following list of dSCAR's internal reserved words: & FIELDS NOAPPEND SAVE ADDITIVE FILE NOEJECT SAY ALIAS FILL NOFOLLOW SCREEN ALL FILTER NOMENU SDF ALTERNATE FOR NOT SECONDARY AND FORM NOUPDATE SELECTION APPLICATION FORMAT OFF STATUS ARRAY FREEZE ON STRUCTURE ASCENDING FROM OR SUMMARY BEFORE FUNCTION OTHERWISE T BLANK GET PAD TAG BOTTOM GETS PAGE TO CASE HEADING PFS TOP CLEAR HISTORY PICTURE TRANSACTION COLOR INDEXES PLAIN TYPE DATABASES INTO POPUPS TYPEAHEAD DECIMALS KEY PRIMARY UNIQUE DEFAULT LABEL PRINT USERS DELIMITED LIKE PROCEDURE USING DELIMITER LOCK QUERY VIEW DESCENDING MACROS RANDOM WAIT DO MARGIN RANGE WHILE DOUBLE MASTER READERROR WIDTH ERROR MEMO RECORD WINDOWS ESCAPE MEMORY RELATION WITH EXCEPT MENUS REPORT EXTENDED MODULE REST ENVIRONMENT NEXT SAMPLE Page 26 OTHER FEATURES & TIPS ────────────────────────────────────────────────────────────────────── ■ Table of Contents dSCAR will create a table of contents for your completed documentation if Modules is toggled on and output is to the printer or print-style to disk. The table of contents tells on which page numbers modules and cross- references are found. ■ Can dSCAR indent my source code properly and still retain a runnable file (without diagramming and line numbers and such)? The answer is yes. To do this for a single file, turn all options off and select file output. dSCAR will generate a file with no diagramming but still indent your code. Error messages are written as comments, thereby not interfering with any interpreter your code is being run through. To do this for a whole system do the same thing but toggle Modules on. ■ Setting Margins on Printer There is a fairly easy way to have dSCAR leave top and bottom margins on your printouts. For a top margin, include in your macro heading several blank lines. For a bottom margin, set your page length to less than it actually is. For example, if your page length is 66 lines, set it to 60--dSCAR will go to the next page at line 60 and leave a bottom margin of six lines. Page 27 CONFIGURING dSCAR ────────────────────────────────────────────────────────────────────── The configuration part of dSCAR is built into the main program. There are no separate configuration files, as the main DSCAR.EXE file will be modified to use your new settings as defaults. The following areas can be modified through configuration: ■ MISCELLANEOUS -- This includes defaults for indentation, file extensions, screen width, printer width and length, printer port, and output headings, to name a few. ■ COLOR -- The different color settings of dSCAR may be modified to suit your monitor and preference. The default settings are set so as to run on a variety of monitors. If you have a color monitor you may opt to use more variety of colors to make the menu and processing screens more appealing. ■ PRINTER SETUP AND RESET -- Define command codes to send to your printer to put it in different modes before and after printing. To run the configuration program, log into the same directory containing DSCAR.EXE and at the DOS prompt type: DSCAR C <return> The 'C' parameter tells dSCAR to run the configuration. Because dSCAR is self-modifying, it needs to know the name and directory under which to find itself. dSCAR will first ask for the .EXE file to modify, including path name. This defaults to DSCAR.EXE in the current directory. However, if dSCAR is not in the current directory or was re-named, you need to answer the question: Name of file to modify (include path): If the file specified is not found in the current directory or directory specified, then dSCAR will tell you so and let you enter it again. If you wish to abort the configuration process at this point, hit <ESC>. If the file to modify is found, then a configuration menu is presented with these five options: 1 - Configure Miscellaneous settings 2 - Install colors 3 - Change printer set-up sequence 4 - Change printer reset sequence 5 - Quit & Save 0 - Quit with No Save At this point select the configuration option you wish to modify. The different configurable features of each section are outlined below. The cursor keys are functional while changing configuration options. Page 28 MISCELLANEOUS SETTINGS ■ Upper, Lower, Proper, Significant, or No change reserved words If Word Fix-Up is selected, dSCAR can change the case of reserved words. Select here the case you wish reserved words to have. Below are samples of each type of case: UPPER: All reserved words are capitalized. ie DO WHILE, ENDDO, SET TALK, RESTORE LOWER: Reserved words are put in lower case ie do while, enddo, set talk, restore PROPER: The first letter of each word is capitalized ie Do While, Enddo, Set Talk, Restore SIGNIFICANT: Only the first four letters are capitalized ie DO WHILe, ENDDo, SET TALK, RESTore NO CHANGE: Leave reserved words as they are found in the code ■ Upper, Lower, Proper, Significant, or No change variables This is the same as above, but specifies what action to take on variables. Thus, you may want to capitalize reserved words and lowercase variables to make your code more readable. ■ Number of spaces to use for indentation This is the indentation increment dSCAR uses when formatting your code to look "pretty." Shown below are two pieces of the same code, the first with an indentation of three and the second with an indentation of five: ┌─INDENT OF THREE────────────────────────────────────────────┐ │ do while count < 100 │ │ if count = 50 then │ │ ? 'Halfway there!' │ │ endif │ │ x = x + 1 │ │ enddo │ └────────────────────────────────────────────────────────────┘ ┌─INDENT OF FIVE─────────────────────────────────────────────┐ │ do while count < 100 │ │ if count = 50 then │ │ ? 'Halfway there!' │ │ endif │ │ x = x + 1 │ │ enddo │ └────────────────────────────────────────────────────────────┘ Page 29 ■ Graphic or Text flow screen diagrams Valid options here are 'G' and 'T'. Graphic diagrams use the IBM extended character set. If your printer does not support these graphic characters then you may wish to turn graphics off. Text diagrams are better for documentation, although graphics are more appealing. Here are two examples of the different flow diagrams: ┌─GRAPHIC FLOW DIAGRAMS──────────────────────────────────────┐ │ │ │ ╓DO WHILE .T. │ │ ║ ACCEPT 'What is your name?' TO Myname │ │ ║ ┌IF UPPER(Myname) <> 'JOE' │ │ ║ │ ? 'Only Joe is allowed access!' │ │ ────────RETURN │ │ ║ ├ELSE │ │ ║ │ ? 'Hello Joe' │ │ ║ │ ╒DO CASE │ │ ║ │ ╞CASE Myname = 'JOE' │ │ ║ │ │ ? 'You typed in uppercase' │ │ ║ │ ╞CASE Myname = 'joe' │ │ ║ │ │ ? 'You typed in lowercase' │ │ ────────────RETURN │ │ ║ │ ╘ENDCASE │ │ ║ └ENDIF │ │ ╙ENDDO │ └────────────────────────────────────────────────────────────┘ ┌─TEXT FLOW DIAGRAMS─────────────────────────────────────────┐ │ │ │ DO WHILE .T. │ │ W ACCEPT 'What is your name?' TO Myname │ │ W IF UPPER(Myname) <> 'JOE' │ │ W T ? 'Only Joe is allowed access!' │ │ <--------RETURN │ │ W ELSE │ │ W F ? 'Hello Joe' │ │ W F DO CASE │ │ W F CASE Myname = 'JOE' │ │ W F 1 ? 'You typed in uppercase' │ │ W F CASE Myname = 'joe' │ │ W F 2 ? 'You typed in lowercase' │ │ <------------RETURN │ │ W F ENDCASE │ │ W ENDIF │ │ ENDDO │ └────────────────────────────────────────────────────────────┘ ■ Truncate lines longer than specified width If a processed line is longer than the specified width (ie 80 Page 30 for the screen, usually) then dSCAR can either break it up using the dBASE continuation character (semicolon), or truncate the line. It is sometimes useful to truncate lines when output is to the screen for flow diagrams, as the output is easier to read. However, for printer and file outputs lines should not be truncated. It is recommended you set this to 'N', as you can set Truncate on temporarily from the dSCAR menu. ■ Use new line number for continuation lines If line numbering is turned on and dSCAR must break up a line, then the line numbering can take one of two formats. If this option is set to 'N' then the continuation line will have the same line number as the first line of the entire command. However, if it is set to 'Y' then each continuation line will have its own line number. Examples follow: ┌─SAME LINE NUMBER FOR CONTINUATION LINES────────────────────┐ │ │ │ 1 SELECT a │ │ 2 RELEASE m0addrf,m0arecf,m0cashf,m0commf,m0custf,; │ │ 2 m0glacf,m0glanf,m0gllkf,m0invof,m0invtf,m0itrnf,; │ │ 2 m0passf,m0recrf,m0scomf,m0tranf,m0ycshf │ │ 3 PUBLIC m0addrf,m0arecf,m0cashf,m0commf,m0custf,m0glacf │ │ 4 USE &m0sysdr.sysdata │ └────────────────────────────────────────────────────────────┘ ┌─NEW LINE NUMBER FOR CONTINUATION LINES─────────────────────┐ │ │ │ 1 SELECT a │ │ 2 RELEASE m0addrf,m0arecf,m0cashf,m0commf,m0custf,; │ │ 3 m0glacf,m0glanf,m0gllkf,m0invof,m0invtf,m0itrnf,; │ │ 4 m0passf,m0recrf,m0scomf,m0tranf,m0ycshf │ │ 5 PUBLIC m0addrf,m0arecf,m0cashf,m0commf,m0custf,m0glacf │ │ 6 USE &m0sysdr.sysdata │ └────────────────────────────────────────────────────────────┘ The second method is handy if you need to reference specific line numbers of a file from within an editor, but the first method is preferred for cross-references. ■ Are you using Clipper? If you are processing mainly Clipper files then answer 'Y' to this question. Clipper does not support comments which span more than one line using the continuation character (;). Therefore, if output is to a file and you are using Clipper, dSCAR will not use continuation characters in the code unless it has to, thereby allowing your Clipper code to be runnable after being processed by dSCAR. If you find that another compiler or dBASE-compatible interpreter has this same problem, then you can answer 'Y' to this question. Page 31 ■ Default extension for dBASE program files dSCAR assumes program files to have an extension of .PRG. However, if you are using a different naming convention you can specify that extension here. ■ Default extension for dSCAR program files When dSCAR sends the output of program and format files to disk, it uses the same filename as the original file, but with a different extension. This extension defaults to .FLO, but can be changed here. ■ Default extension for dSCAR cross-references files Cross-reference outputs will have the same filename as the module being processed, but with a new extension. This extension defaults to .XRF, but can be specified differently. ■ Default extension for dSCAR printer files If output is to a file printer-style, then dSCAR writes to a file with the same filename and new extension. This extension defaults to .PRN, but can be changed. ■ Strip drive and path from filenames Respond with 'Y' if you want to strip drive and pathnames from files encountered in processing. If they are not stripped, dSCAR will look in the paths specified. Regardless of what this option is set to, dSCAR always recognizes and uses any path prefixed to the main file you enter at start-up. This option is especially important when the Modules option is turned on. ■ Number of lines to display per output screen This should be defaulted to stop and wait for a keypress when one full page has been displayed. But, if you happen to want to display only ten lines before stopping, or perhaps two pages, you can change it with this option. ■ Number of columns across output screen This determines where to break a long line at. If want to break lines at 40 characters, then specify 40. Or if you happen to have a wide display then you can increase the number of columns. The default is 80. ■ Number of lines per page on your printer The printer length tells dSCAR how many lines are on the paper so that it can issue a formfeed at the proper time to skip over the Page 32 perforation. The default should work for paper that is the standard 11 inches long. You may have to experiment with this setting if you are using a laser printer. ■ Column width of your printer This is the number of printable characters across each printer page. The default value of 80 should work with most printers. However, you will have to change this if you are using a wide carriage printer so that dSCAR will print all the way across the page. If you set your printer to condensed mode you may have to change this value. ■ Left margin for printer output Specify this value in number of spaces to indent. For example, enter 5 to indent five spaces before printing each line, or 0 for no left margin. Margins are especially useful if you plan on hole-punching your reports. ■ Number of characters per line for file output This is basically the same as the screen width, but instead indicates when to break a long line when output is to a file. Some people may want to display a screen width, but others may want to go as far as 255 characters. ■ Default printer port dSCAR supports printer ports 1, 2, and 3. dSCAR will send printer output to the port specified. ■ Issue a formfeed after each module If you wish each module and every cross-reference to appear on its own page when output is to printer, then have dSCAR send a form feed after each module. However, answer NO if you wish to save paper and not start each module on a separate page. ■ Report heading for printer reports On the top of each printer page, dSCAR can optionally print a header containing such information as module name, dSCAR version, current date, page number, and more. This header is user-definable, and can contain straight text or macro commands. Macro commands will print dynamic information such as page number, module being processed, date, and dSCAR version number. Straight text can contain a copyright notice, your company name, or anything else you desire. The header is entered in a three-line format. If you run out of room for the header text and macros, hit <return> to get to the next Page 32 line and continue entering the header. Each of the three lines is strung together and treated as one long heading line. Note that each line of entry does NOT represent one line on the printer. Macro commands are one uppercase character and are preceded by the ampersand character (&), except for the new line macro which is a single back slash (\). Macro values are printed exactly where they are found in the header line configuration. Below is a list of the macro commands available: Macro Meaning Picture --------------------------------- &P page number 9999 &D date Mon DD, year &T time 99:99am &V version 9.99 BETA &S system name &M current module &F path+module &= procedure being displayed if specific procedure selected && print the ampersand character (&) \ newline (use as many lines as you want in the heading) Remember that macro characters MUST BE IN UPPERCASE! Here are some example macro headings and how they would print: ---------------- MACRO: dSCAR v&V &D &T\SYSTEM: &S dSCAR v3.0 Dec 29, 1988 10:41pm SYSTEM: LIBRARY ---------------- MACRO: Copyright (c) 1989 by John Smith.\\&M\&F\Page &P\ Copyright (c) 1989 by John Smith. ADDBOOK.PRG \DBASE\LIBRARY\ADDBOOK.PRG Page 10 ---------------- The second example shows how to use the new line character (\). A newline can be placed anywhere, and doubling new line characters will add a blank line. By putting several new line characters at the end of a macro heading you can effectively space between the header and the body of your report. INSTALL COLORS The colors dSCAR uses for its menus and output display can be configured to your preference. When color installation is selected, Page 33 the available colors are drawn across the screen with the letters A-P denoting each color. There are nine different color objects. For each object specify a foreground and background color by selecting the letter representing the desired color. Note that only colors A-H are available for background colors! Below is a description of each color item: ■ Source line -- this is the color for the display of your source code ■ Line numbers -- if line numbers is turned on, the line numbers will be in this color ■ Error Messages -- any error messages, in processing or on the menu screen, will show up as this color ■ Diagramming -- if diagramming is turned on, the screen diagrams will be highlighted in this color ■ Footer message -- this is the message at the bottom of the processing screen indicating the current module being processed ■ Selected options -- selected options on the menu screen will be indicated by highlighting in this color ■ Un-selected options -- menu options which are turned off (unselected) will be displayed in this color ■ Window color -- this is the color for the window border on the menu screen ■ Window titles -- the titles above menu options and title headings of the different windows will show up in this color The best way to configure the color is to select some appealing colors, run dSCAR, and then try again if the colors did not turn out how you like them. Keep in mind that the main background color within a window and on the processing screen will ALWAYS be black. PRINTER SETUP AND RESET dSCAR can automatically send setup codes to your printer when output to printer is selected. This is useful if you want your printer to go into condensed mode, be reset, or have the page length reset before any reports are printed. In addition, dSCAR can optionally send codes after it is done Page 34 printing, perhaps to reset the printer to its original settings. To enter setup codes, select option 3 from the configuration menu. Option 4 allows you to enter reset codes. Upon entering either printer setup or reset, you are prompted to enter print code #1. A print code is a single character--whether it be a control character or alphanumeric character--which will be sent to the printer. For example, the ESCape code and the letter 'A' both represent single print codes. Up to 40 print codes may be sent for the setup sequence, and an additional 40 for the reset sequence. To enter an alphanumeric print code, just hit the key on the keyboard. For example, to send the letter 'A' to the printer, hit the 'A' key. To send the '@' symbol, hit that key on the keyboard. Control codes are entered by typing the '#' key (pound sign). A '#' tells dSCAR that the next characters are ascii codes. For example, to enter ESCape as a print code, type '#' and then type in '27' (followed by the <return> key). To enter the '#' key as a print code, type '#' and then '35', as 35 is the ascii code for the pound character. When you are all done entering print codes, press the <ESC> key (remember, to have the ESCape character be a print code, you must enter the ascii code for it). Option 5 from the configuration menu will save your new settings to the executable dSCAR file and then exit configuration. If you do not want to save the changes made, then select option 0 to exit without writing the configuration. Page 35 ABOUT THE AUTHOR & THE PROGRAM ────────────────────────────────────────────────────────────────────── The first version of dSCAR was released in 1986 as user supported software. Version 1.0 was followed by 2.0 and then 2.3a. Version 3.0 is almost twice as fast as version 2.3 and has a multitude of additional features. In 1988 I was contacted by a large software publishing firm interested in buying dSCAR. I turned down their offer with the idea that dSCAR would be more successful if it continued to be marketed by me. In successful I mean: 1) I could enhance the program to my specifications and continue to update it at my convenience; and 2) financially I could do better selling dSCAR as user supported software than to take what the publisher offered me. During the 1989 summer break I did not seek a "real" job so that I could release dSCAR v3.0. I am hoping sales of dSCAR will put me through four years of college at Cal Poly in San Luis Obispo, beginning in the fall of 1989. Why was version 3.0 so slow in coming? Time was the number one culprit. In addition to going to school I run track & field (10.7sec for 100m, 21.9 for 200m, 48.50 for 400m). I hope to continue my running at Cal Poly, but will have someone else handle the dSCAR orders. dSCAR was not a one-man effort. In addition to the registrants who provided monetary support and comments before v3.0, I wish to thank the following individuals for their beta-testing, support, or suggestions: Randy Wallin, Gene Head, Todd Natkin, Bruce Bott, Kent Riesen, Rod Ledbetter, P. Olympia, Ed Albert, Jon Love, Larry Taylor, and Scott Ponder. Page 36